---
title: Command Reference
description: Complete reference for all CUA CLI commands
---

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Overview

The CUA CLI provides commands for authentication and sandbox management.

### Command Styles

The CLI supports **two command styles** for flexibility:

**Flat style** (quick & concise):

```bash
cua list
cua create --os linux --size small --region north-america
cua start my-sandbox
```

**Grouped style** (explicit & clear):

```bash
cua sb list         # or: cua sandbox list
cua sb create       # or: cua sandbox create
cua sb start        # or: cua sandbox start
```

Both styles work identically - use whichever you prefer!

### Available Commands

- **Authentication** - `cua auth login`, `cua auth env`, `cua auth logout` (also available as flat commands: `cua login`, `cua env`, `cua logout`)
- **Sandbox Management** - `cua list`, `cua create`, `cua get`, `cua start`, `cua stop`, `cua restart`, `cua delete`, `cua vnc`

## Authentication Commands

### `cua auth login`

Authenticate with your CUA account using browser-based OAuth flow.

```bash
# Interactive browser login
cua auth login

# Direct API key login
cua auth login --api-key sk-your-api-key-here

# Alternative flat style
cua login
cua login --api-key sk-your-api-key-here
```

**Options:**

- `--api-key <key>` - Provide API key directly instead of browser flow

**Example:**

```bash
$ cua auth login
Opening browser for CLI auth...
API key saved
```

### `cua auth env`

Create or update a `.env` file in the current directory with your CUA API key.

```bash
cua auth env

# Alternative flat style
cua env
```

**Example:**

```bash
$ cua auth env
Wrote /path/to/your/project/.env
```

The generated `.env` file will contain:

```
CUA_API_KEY=sk-your-api-key-here
```

### `cua auth logout`

Remove the stored API key from your system.

```bash
cua auth logout

# Alternative flat style
cua logout
```

**Example:**

```bash
$ cua auth logout
Logged out
```

## Sandbox Commands

### `cua list`

List all your sandboxes with their current status. Passwords are hidden by default for security.

```bash
# List sandboxes (passwords hidden)
cua list

# Show passwords explicitly
cua list --show-passwords

# Alternative aliases
cua ls
cua ps
```

**Example Output (default, passwords hidden):**

```
NAME              STATUS    HOST
my-dev-sandbox    running   my-dev-sandbox.sandbox.cua.ai
test-windows      stopped   test-windows.sandbox.cua.ai
```

**Example Output (with --show-passwords):**

```
NAME              STATUS    PASSWORD           HOST
my-dev-sandbox    running   secure-pass-123    my-dev-sandbox.sandbox.cua.ai
test-windows      stopped   another-pass-456   test-windows.sandbox.cua.ai
```

### `cua create`

Create a new sandbox.

```bash
cua create --os <OS> --size <SIZE> --region <REGION>
```

**Required Options:**

- `--os` - Operating system: `linux`, `windows`, `macos`
- `--size` - Sandbox size: `small`, `medium`, `large`
- `--region` - Region: `north-america`, `europe`, `asia-pacific`, `south-america`

**Examples:**

```bash
# Create a small Linux sandbox in North America
cua create --os linux --size small --region north-america

# Create a medium Windows sandbox in Europe
cua create --os windows --size medium --region europe

# Create a large macOS sandbox in Asia Pacific
cua create --os macos --size large --region asia-pacific
```

**Response Types:**

**Immediate (Status 200):**

```bash
Sandbox created and ready: my-new-sandbox-abc123
Password: secure-password-here
Host: my-new-sandbox-abc123.sandbox.cua.ai
```

**Provisioning (Status 202):**

```bash
Sandbox provisioning started: my-new-sandbox-abc123
Job ID: job-xyz789
Use 'cua list' to monitor provisioning progress
```

### `cua get`

Get detailed information about a specific sandbox, including computer-server health status.

```bash
cua get <name>

# With additional options
cua get <name> --json
cua get <name> --show-passwords
cua get <name> --show-vnc-url
```

**Options:**

- `--json` - Output all details in JSON format
- `--show-passwords` - Include password in output
- `--show-vnc-url` - Include computed NoVNC URL

**Example Output (default):**

```bash
$ cua get my-dev-sandbox
Name: my-dev-sandbox
Status: running
Host: my-dev-sandbox.containers.cloud.trycua.com
OS Type: linux
Computer Server Version: 0.1.30
Computer Server Status: healthy
```

**Example Output (with --show-passwords and --show-vnc-url):**

```bash
$ cua get my-dev-sandbox --show-passwords --show-vnc-url
Name: my-dev-sandbox
Status: running
Host: my-dev-sandbox.containers.cloud.trycua.com
Password: secure-pass-123
OS Type: linux
Computer Server Version: 0.1.30
Computer Server Status: healthy
VNC URL: https://my-dev-sandbox.containers.cloud.trycua.com/vnc.html?autoconnect=true&password=secure-pass-123
```

**Example Output (JSON format):**

```bash
$ cua get my-dev-sandbox --json
{
  "name": "my-dev-sandbox",
  "status": "running",
  "host": "my-dev-sandbox.containers.cloud.trycua.com",
  "os_type": "linux",
  "computer_server_version": "0.1.30",
  "computer_server_status": "healthy"
}
```

**Computer Server Health Check:**

The `cua get` command automatically probes the computer-server when the sandbox is running:

- Checks OS type via `https://{host}:8443/status`
- Checks version via `https://{host}:8443/cmd`
- Shows "Computer Server Status: healthy" when both probes succeed
- Uses a 3-second timeout for each probe

<Callout type="info">
  The computer server status is only checked for running sandboxes. Stopped or suspended sandboxes
  will not show computer server information.
</Callout>

### `cua start`

Start a stopped sandbox.

```bash
cua start <name>
```

**Example:**

```bash
$ cua start my-dev-sandbox
Start accepted
```

### `cua stop`

Stop a running sandbox.

```bash
cua stop <name>
```

**Example:**

```bash
$ cua stop my-dev-sandbox
stopping
```

### `cua restart`

Restart a sandbox.

```bash
cua restart <name>
```

**Example:**

```bash
$ cua restart my-dev-sandbox
restarting
```

### `cua delete`

Delete a sandbox permanently.

```bash
cua delete <name>
```

**Example:**

```bash
$ cua delete old-test-sandbox
Sandbox deletion initiated: deleting
```

<Callout type="warn">
  This action is irreversible. All data on the sandbox will be permanently lost.
</Callout>

### `cua vnc`

Open the VNC interface for a sandbox in your browser.

```bash
cua vnc <name>

# Alternative alias
cua open <name>
```

**Example:**

```bash
$ cua vnc my-dev-sandbox
Opening NoVNC: https://my-dev-sandbox.sandbox.cua.ai/vnc.html?autoconnect=true&password=...
```

This command automatically opens your default browser to the VNC interface with the correct password pre-filled.

## Global Options

### Help

Get help for any command:

```bash
cua --help
cua auth login --help
cua create --help
cua list --help
```

## Error Handling

The CLI provides clear error messages for common issues:

### Authentication Errors

```bash
$ cua list
Unauthorized. Try 'cua auth login' again.
```

### Sandbox Not Found

```bash
$ cua start nonexistent-sandbox
Sandbox not found
```

### Invalid Configuration

```bash
$ cua create --os invalid --configuration small --region north-america
Invalid request or unsupported configuration
```

## Tips and Best Practices

### 1. Use Descriptive Sandbox Names

```bash
# Good
cua create --os linux --size small --region north-america
# Then rename or use meaningful names in the dashboard

# Better workflow
cua list  # Check the generated name
# Use that name consistently
```

### 2. Environment Management

```bash
# Set up your project with API key
cd my-project
cua auth env
# Now your project has CUA_API_KEY in .env
```

### 3. Quick Sandbox Access

```bash
# Create aliases for frequently used sandboxes
alias dev-sandbox="cua vnc my-development-sandbox"
alias prod-sandbox="cua vnc my-production-sandbox"
```

### 4. Monitoring Provisioning

```bash
# For sandboxes that need provisioning time
cua create --os windows --size large --region europe
# Sandbox provisioning started: my-sandbox-abc123
# Job ID: job-xyz789

# Check status periodically
watch -n 5 cua list
```

## Next Steps

- [Get started with the quickstart guide](/get-started/quickstart#cli-quickstart)
- [Learn about CUA computers](/computer-sdk/computers)
- [Explore agent automation](/agent-sdk/agent-loops)
